package com.google.code.jholidays.events;

import java.util.Date;

import com.google.code.jholidays.core.EventDescriptor;

/**
 * Represents interface for all events. For skeletal implementation see
 * {@link AbstractEvent}
 * 
 * @author tillias
 * 
 */
public interface IEvent {

    /**
     * Returns date on which event should occur in given year
     * <p>
     * Method doesn't throw any exceptions on errors. If error occurred returns
     * <code>null</code> instead
     * 
     * @param year
     *            Year to which occurrence date belongs
     * @return Valid date on which event should occur if method succeeds, null
     *         pointer otherwise
     */
    Date getDate(int year);

    /**
     * Returns event identifier. Each event has unique identifier.
     * 
     * @return Event identifier
     */
    int getID();

    /**
     * Gets event name
     * 
     * @return Event name
     */
    String getName();

    /**
     * Gets event textual description
     * 
     * @return Event description
     */
    String getDescription();

    /**
     * Returns valid not-null descriptor associated with given event
     * 
     * @return Event descriptor
     */
    EventDescriptor getDescriptor();
}
